Initializing and Terminating QuickDraw 3D

Before calling any QuickDraw 3D routines, you need to verify that the QuickDraw 3D software is available in the current operating environment. Then you need to create and initialize a connection to the QuickDraw 3D software.

On the Mac OS, you can verify that QuickDraw 3D is available by calling the MyEnvironmentHasQuickDraw3D function defined in Listing 1 .

Listing 1 Determining whether QuickDraw 3D is available

Boolean MyEnvironmentHasQuickDraw3D (void)
{
    return (long) Q3Initialize != kUnresolvedSymbolAddress;
}


The MyEnvironmentHasQuickDraw3D function checks to see whether the address of the Q3Initialize function has been resolved. If it hasn't been resolved (that is, if the Code Fragment Manager couldn't find the QuickDraw 3D shared library when launching your application), MyEnvironmentHasQuickDraw3D returns the value FALSE to its caller. Otherwise, if the address of the Q3Initialize function was successfully resolved, MyEnvironmentHasQuickDraw3D returns TRUE .

For the function MyEnvironmentHasQuickDraw3D to work properly, you must establish soft links (also called weak links ) between your application and the QuickDraw 3D shared library. For information on soft links, see the book Inside Macintosh: PowerPC System Software. For specific information on establishing soft links, see the documentation for your software development system.

On the Mac OS, you can verify that QuickDraw 3D is available in the current operating environment by calling the Gestalt function with the gestaltQD3D selector. Gestalt returns a long word whose value indicates the availability of QuickDraw 3D. Currently these values are defined:

enum {
    gestaltQD3DNotPresent                       = 0,
    gestaltQD3DAvailable                        = 1
}


You should ensure that the value gestaltQD3DAvailable is returned before calling any QuickDraw 3D routines.

For more information on the Gestalt function, see Inside Macintosh: Operating System Utilities .

You create and initialize a connection to the QuickDraw 3D software by calling the Q3Initialize function, as illustrated in Listing 2 .

Listing 2 Initializing a connection with QuickDraw 3D

OSErr MyInitialize (void)
{
    TQ3Status           myStatus;
    
    myStatus = Q3Initialize();              /*initialize QuickDraw 3D*/
    if (myStatus == kQ3Failure)
        DebugStr("\pQ3Initialize returned failure.");
    
    return (noErr);
}


Once you've successfully called Q3Initialize , you can safely call other QuickDraw 3D routines. If Q3Initialize returns unsuccessfully (as indicated by the kQ3Failure result code), you shouldn't call any QuickDraw 3D routines other than the error-reporting routines (such as Q3Error_Get or Q3Error_IsFatalError ) or the Q3IsInitialized function. See the chapter "Error Manager" for details on QuickDraw 3D's error-handling capabilities.

When you have finished using QuickDraw 3D, you should call Q3Exit to close your connection with QuickDraw 3D. In most cases, you'll do this when terminating your application. Listing 3 illustrates how to call Q3Exit .

Listing 3 Terminating QuickDraw 3D

void MyFinishUp (void)
{
    TQ3Status           myStatus;
    
    myStatus = Q3Exit();                /*unload QuickDraw 3D*/
    if (myStatus == kQ3Failure)
        DebugStr("\pQ3Exit returned failure.");
}


---

© 1997 Apple Computer, Inc.

Previous | QD3D Book | Overview | Chapter Contents | Next |